<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>t_optmgmt</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<xref type="10" name="optmgmt"></xref>
<h4>NAME</h4><blockquote>
t_optmgmt - manage options for a transport endpoint
</blockquote><h4>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="xti.h.html">xti.h</a>&gt;

int t_optmgmt(
    int fd,
    const struct t_optmgmt *req,
    struct t_optmgmt *ret)
</code>
</pre>
</blockquote><h4>DESCRIPTION</h4><blockquote>
<pre>
<P><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Parameters</b>
<th align=center><b>Before call</b>
<th align=center><b>After call</b>
<tr valign=top><td align=left>fd
<td align=center>x
<td align=center>/
<tr valign=top><td align=left>req-&gt;opt.maxlen
<td align=center>=
<td align=center>=
<tr valign=top><td align=left>req-&gt;opt.len
<td align=center>x
<td align=center>=
<tr valign=top><td align=left>req-&gt;opt.buf
<td align=center>x (x)
<td align=center>=
<tr valign=top><td align=left>req-&gt;flags
<td align=center>x
<td align=center>=
<tr valign=top><td align=left>ret-&gt;opt.maxlen
<td align=center>x
<td align=center>=
<tr valign=top><td align=left>ret-&gt;opt.len
<td align=center>/
<td align=center>x
<tr valign=top><td align=left>ret-&gt;opt.buf
<td align=center>?
<td align=center>(?)
<tr valign=top><td align=left>ret-&gt;flags
<td align=center>/
<td align=center>x
</table>
</pre>
<p>
The
<i>t_optmgmt()</i>
function enables a transport user to retrieve,
verify or negotiate protocol options with the transport provider.
The argument
<I>fd</I>
identifies a transport endpoint.
<p>
The
<I>req</I>
and
<I>ret</I>
arguments point to a
<B>t_optmgmt</B>
structure containing the following members:
<pre>
<code>
struct      netbuf opt;
t_scalar_t  flags;
</code>
</pre>
<p>
The
<I>opt</I>
field identifies protocol options
and the
<I>flags</I>
field is used to specify the action to take with those options.
<p>
The options are represented by a
<B>netbuf</B>
structure
in a manner similar to the address in
<i><a href="t_bind.html">t_bind()</a></i>.
The argument
<I>req</I>
is used to request a specific action of the provider and to send options
to the provider.  The argument
<I>len</I>
specifies the number of bytes in the options,
<I>buf</I>
points to the options buffer, and
<I>maxlen</I>
has no meaning for the
<I>req</I>
argument.
The transport provider may return options and flag values to the
user through
<I>ret</I>.
For
<I>ret</I>,
<I>maxlen</I>
specifies the maximum size of the options buffer and
<I>buf</I>
points to the buffer where the options are to be placed.
If 
<I>maxlen</I>
in 
<I>ret</I>
is set to zero, no options values are returned.
On return,
<I>len</I>
specifies the number of bytes of options returned.
The value in
<I>maxlen</I>
has no meaning for the
<I>req</I>
argument, but must be set in the
<I>ret</I>
argument to specify the maximum number of bytes the options buffer can hold.
<p>
Each option in the options buffer is of the form
<B>struct t_opthdr</B>
possibly followed by an option value.
<p>
The
<I>level</I>
field of
<B>struct t_opthdr</B>
identifies the XTI level or a protocol of the transport provider.
The
<I>name</I>
field identifies the option within the level, and
<I>len</I>
contains its
total length; that is, the length of the option header
<B>t_opthdr</B>
plus the length of the option value.  If
<i>t_optmgmt()</i>
is called with the action T_NEGOTIATE set, the
<I>status</I>
field of the returned options
contains information about the success or failure of a negotiation.
<p>
Several options can be concatenated. The option user has, however to
ensure that each options header and value part starts at a boundary
appropriate for the architecture-specific alignment rules. The
macros
T_OPT_FIRSTHDR(nbp), T_OPT_NXTHDR(nbp, tohp), T_OPT_DATA(tohp)
are provided for that purpose.
<dl compact>

<dt>T_OPT_DATA<dd>If argument is a pointer to a
<B>t_opthdr</B>
structure, this macro returns an unsigned character pointer
to the data associated with the
<B>t_opthdr</B>.

<dt>T_OPT_NXTHDR<dd>If the first argument is a pointer to a
netbuf structure associated with an option
buffer and second argument is a pointer to a
<B>t_opthdr</B>
structure within that option buffer,
this macro returns a pointer to the next
<B>t_opthdr</B>
structure or a null pointer if this
<B>t_opthdr</B>
is the last
<B>t_opthdr</B>
in the option buffer.

<dt>T_OPT_FIRSTHDR<dd>If the argument is a pointer to a
<B>netbuf</B>
structure associated with an option
buffer, this macro returns the pointer to the first
<B>t_opthdr</B>
structure in the associated
option buffer, or a null pointer if there is
no option buffer associated with this
<B>netbuf</B>
or if it is not possible or the associated
option buffer is too small to accommodate
even the first aligned option header.

</dl>
<p>
T_OPT_FIRSTHDR is useful for finding
an appropriately aligned start of the option buffer.
T_OPT_NEXTHDR is useful for moving to the start
of the next appropriately aligned
option in the option buffer. Note that
OPT_NEXTHDR is also available for backward compatibility
requirements. T_OPT_DATA is useful for finding the start of
the data part in the option buffer where the contents of its
values start on an appropriately aligned boundary.
<p>
If the transport user specifies several options on input, all options
must address the same level.
<p>
If any option in the options buffer does not indicate the same
level as the first option, or the level specified is unsupported,
then the
<i>t_optmgmt()</i>
request will fail with [TBADOPT].
If the error is detected, some options have possibly been successfully
negotiated.
The transport user can check the current status by calling
<i>t_optmgmt()</i>
with the T_CURRENT flag set.
<p>
<xref href=chap5></xref>
contains a detailed description about the use of options
and should be read before using this function.
<p>
The
<I>flags</I>
field of
<I>req</I>
must specify one of the following actions:
<dl compact>

<dt>T_NEGOTIATE<dd>This action enables the transport user to negotiate option values.

The user specifies the options of interest and their values in the buffer
specified by
<I>req-&gt;opt.buf</I>
and
<I>req-&gt;opt.len</I>.
The negotiated option values are returned in the buffer pointed to by
<I>ret-&gt;opt.buf</I>.
The
<I>status</I>
field of each returned option is set to indicate the result of the
negotiation.
The value is T_SUCCESS if the proposed value was negotiated,
T_PARTSUCCESS if a degraded value was negotiated, T_FAILURE if the
negotiation failed (according to the negotiation rules), T_NOTSUPPORT if
the transport provider does not support this option or illegally requests
negotiation of a privileged option, and T_READONLY if modification of a
read-only option was requested.
If the status is T_SUCCESS, T_FAILURE, T_NOTSUPPORT or T_READONLY,
the returned option value is the same as the one requested on input.

The overall result of the negotiation is returned in
<I>ret-&gt;flags</I>.

This field contains the worst single result, whereby the rating is done
according to the order T_NOTSUPPORT, T_READONLY, T_FAILURE, T_PARTSUCCESS,
T_SUCCESS.
The value T_NOTSUPPORT is the worst result and T_SUCCESS is the best.

For each level, the option T_ALLOPT (see below) can be requested on input.
No value is given with this option; only the
<B>t_opthdr</B>
part is specified.
This input requests to negotiate all supported options
of this level to their default values.
The result is returned option by option in
<I>ret-&gt;opt.buf</I>.
(Note that depending on the state of the transport endpoint, not all
requests to negotiate the default value may be successful.)

<dt>T_CHECK<dd>This action enables the user to verify whether the options specified in
<I>req</I>
are supported by the transport provider.

If an option is specified with no option value (it consists only of a
<B>t_opthdr</B>
structure), the option is returned with its
<I>status</I>
field set to T_SUCCESS if
it is supported, T_NOTSUPPORT if it is not or needs additional user
privileges, and T_READONLY if it is read-only (in the current XTI state).
No option value is returned.

If an option is specified with an option value, the
<I>status</I>
field of the returned option has the same value, as if the user had
tried to negotiate this value with T_NEGOTIATE.
If the status is T_SUCCESS, T_FAILURE, T_NOTSUPPORT or T_READONLY, the
returned option value is the same as the one requested on input.

The overall result of the option checks is returned in
<I>ret-&gt;flags</I>.
This field contains the worst single result of the option checks, whereby the
rating is the same as for T_NEGOTIATE.

Note that no negotiation takes place.
All currently effective option values remain unchanged.

<dt>T_DEFAULT<dd>This action enables the transport user to retrieve the default option
values.
The user specifies the options of interest in
<I>req-&gt;opt.buf</I>.
The option values are irrelevant and will be ignored;
it is sufficient to specify the
<B>t_opthdr</B>
part of an option only.
The default values are then returned in
<I>ret-&gt;opt.buf</I>.

The <I>status</I> field returned is T_NOTSUPPORT if the protocol
level does not support this option or the transport user illegally
requested a privileged option, T_READONLY if the option is read-only,
and set to T_SUCCESS in all other cases.
The overall result of the request is returned in
<I>ret-&gt;flags</I>.
This field contains the worst single result, whereby the rating is the
same as for T_NEGOTIATE.

For each level, the option T_ALLOPT (see below) can be requested on input.
All supported options of this level with their default values are then
returned.
In this case,
<I>ret-&gt;opt.maxlen</I>
must be given at least the value
<I>info-&gt;options</I>
(see
<i><a href="t_getinfo.html">t_getinfo()</a></i>,
<i><a href="t_open.html">t_open()</a></i>)
before the call.

<dt>T_CURRENT<dd>This action enables the transport user to retrieve the currently effective
option values.
The user specifies the options of interest in
<I>req-&gt;opt.buf</I>.
The option values are irrelevant and will be ignored;
it is sufficient to specify the
<B>t_opthdr</B>
part of an option only.
The currently effective values are then returned in
<I>ret-&gt;opt.buf</I>.

The <I>status</I> field returned is T_NOTSUPPORT if the protocol
level does not support this option or the transport user illegally
requested a privileged option, T_READONLY if the option is read-only,
and set to T_SUCCESS in all other cases.
The overall result of the request is returned in
<I>ret-&gt;flags</I>.
This field contains the worst single result, whereby the rating is the
same as for T_NEGOTIATE.

For each level, the option T_ALLOPT (see below) can be requested on input.
All supported options of this level with their currently effective
values are then returned.

</dl>
<p>
The option T_ALLOPT can only be used with
<i>t_optmgmt()</i>
and the actions T_NEGOTIATE, T_DEFAULT and T_CURRENT.  It can be used with any
supported level and addresses all supported options of this level.  The option
has no value; it consists of a
<B>t_opthdr</B>
only.  Since in a
<i>t_optmgmt()</i>
call only options of one level may be addressed, this option should not be
requested together with other options.
The function returns as soon as this option has been processed.
<p>
Options are independently processed in the order they appear in the input
option buffer.
If an option is multiply input, it depends on the implementation
whether it is multiply output or whether it is returned only once.
<p>
Transport providers may not be able to provide an interface
capable of supporting T_NEGOTIATE and/or T_CHECK functionalities.
When this is the case, the error [TNOTSUPPORT] is returned.
<p>
The function
<i>t_optmgmt()</i>
may block under various circumstances
and depending on the implementation.
The function will block, for instance, if the protocol addressed by
the call resides on a separate controller.
It may also block due to flow control constraints; that is, if data
sent previously across this transport endpoint has not yet been fully
processed.
If the function is interrupted by a signal, the option negotiations
that have been done so far may remain valid.
The behaviour of the function is not changed if O_NONBLOCK is set.
</blockquote><h4>XTI-LEVEL OPTIONS</h4><blockquote>
XTI-level options are not specific for a particular transport provider.
An XTI implementation supports none, all or any subset of the options
defined below.
An implementation may restrict the use of any of these options by
offering them only in the privileged or read-only mode,
or if
<I>fd</I>
relates to specific transport providers.
<p>
The subsequent options do not have end-to-end significance
(see 
<xref href=xtioptions></xref>).
They may be negotiated in all XTI states except T_UNINIT.
<br>
<p>
The protocol level is XTI_GENERIC.
For this level, the following options are defined:
<P><table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>option name</b>
<th align=center><b>type of option</b>
<th align=center><b>legal</b>
<th align=center><b>meaning</b>
<tr valign=top><th align=center><b></b>
<th align=center><b>value</b>
<th align=center><b>option value</b>
<th align=center><b></b>
<tr valign=top><td align=left>XTI_DEBUG
<td align=left>array of t_uscalar_t
<td align=left>see text
<td align=left>enable debugging
<tr valign=top><td align=left>XTI_LINGER
<td align=left>struct t_linger
<td align=left>see text
<td align=left> linger on close if data is present 
<tr valign=top><td align=left>XTI_RCVBUF
<td align=left>t_uscalar_t
<td align=left>size in octets
<td align=left>receive buffer size
<tr valign=top><td align=left>XTI_RCVLOWAT
<td align=left>t_uscalar_t
<td align=left>size in octets
<td align=left>receive low-water mark
<tr valign=top><td align=left>XTI_SNDBUF
<td align=left>t_uscalar_t
<td align=left>size in octets
<td align=left>send buffer size
<tr valign=top><td align=left>XTI_SNDLOWAT
<td align=left>t_uscalar_t
<td align=left>size in octets
<td align=left>send low-water mark
</table>
<h6 align=center><xref table="XTI-level Options"></xref>Table: XTI-level Options</h6>
<p>
A request for XTI_DEBUG is an absolute requirement.
A request to activate XTI_LINGER is an absolute requirement;
the timeout value to this option is not.
XTI_RCVBUF, XTI_RCVLOWAT, XTI_SNDBUF and XTI_SNDLOWAT are not absolute
requirements.
<dl compact>

<dt>XTI_DEBUG<dd>This option enables debugging.
The values of this option are implementation-defined.
Debugging is disabled if the option is specified with &quot;no value&quot;;
that is, with an option header only.

The system supplies utilities to process the traces.
Note that an implementation may also provide other means for
debugging.

<dt>XTI_LINGER<dd>This option is used to linger the execution of a
<i><a href="t_close.html">t_close()</a></i>
or
<i><a href="close.html">close()</a></i>
if send data is still queued in the send buffer.
The option value specifies the linger period.
If a
<i><a href="close.html">close()</a></i>
or
<i><a href="t_close.html">t_close()</a></i>
is issued and the send buffer is not empty, the system attempts to send the
pending data within the linger period before closing the endpoint.  Data still
pending after the linger period has elapsed is discarded.

Depending on the implementation,
<i><a href="t_close.html">t_close()</a></i>
or
<i><a href="close.html">close()</a></i>
either block for at
maximum the linger period, or immediately return, whereupon the system holds
the connection in existence for at most the linger period.

The option value consists of a structure
<B>t_linger</B>
declared as:
<pre>
<code>
struct t_linger {
    t_scalar_t l_onoff;   /* switch option on/off     */
    t_scalar_t l_linger;  /* linger period in seconds */
}
</code>
</pre>


Legal values for the field
<I>l_onoff</I>
are:
<pre>
<dl compact><dt> <dd>
T_NO    switch option off
T_YES   activate option
</dl>
</pre>
<p>
The value
<I>l_onoff</I>
is an absolute requirement.
<p>
The field
<I>l_linger</I>
determines the linger period in seconds.
The transport user can request the default value by setting the field
to T_UNSPEC.
The default timeout value depends on the underlying transport provider
(it is often T_INFINITE).
Legal values for this field are
T_UNSPEC, T_INFINITE and all non-negative numbers.
<p>
The
<I>l_linger</I>
value is not an absolute requirement.
The implementation may place upper and lower limits to this value.
Requests that fall short of the lower
limit are negotiated to the lower limit.
<p>
Note that this option does not linger the execution of
<i><a href="t_snddis.html">t_snddis()</a></i>.
<p>
<dt>XTI_RCVBUF<dd>This option is used to adjust the internal buffer size allocated for the
receive buffer.
The buffer size may be increased for high-volume connections,
or decreased to limit the possible backlog of incoming data.
<p>
This request is not an absolute requirement.
The implementation may place upper and lower limits on the option value.
Requests that fall short of the lower limit are negotiated to the lower limit.
<p>
Legal values are all positive numbers.
<p>
<dt>XTI_RCVLOWAT<dd>This option is used to set a low-water mark in the receive buffer.
The option value gives the minimal number of bytes that must have
accumulated in the
receive buffer before they become visible to the transport user.
If and when the
amount of accumulated receive data exceeds the low-water mark, a T_DATA
event is created, an event mechanism (for example,
<i><a href="poll.html">poll()</a></i>
or
<i><a href="select.html">select()</a></i>)
indicates the data, and the data can be read by
<i><a href="t_rcv.html">t_rcv()</a></i>
or
<i><a href="t_rcvudata.html">t_rcvudata()</a></i>.
<p>
This request is not an absolute requirement.
The implementation may place upper and lower limits on the option value.
Requests that fall short of the lower limit are negotiated to the lower limit.
<p>
Legal values are all positive numbers.
<p>
<dt>XTI_SNDBUF<dd>This option is used to adjust the internal buffer size allocated for the
send buffer.
<p>
This request is not an absolute requirement.
The implementation may place upper and lower limits on the option value.
Requests that fall short of the lower limit are negotiated to the lower limit.
<p>
Legal values are all positive numbers.
<p>
<dt>XTI_SNDLOWAT<dd>This option is used to set a low-water mark in the send buffer.
The option
value gives the minimal number of bytes that must have accumulated in the
send buffer before they are sent.
<p>
This request is not an absolute requirement.
The implementation may place upper and lower limits on the option value.
Requests that fall short of the lower limit are negotiated to the lower limit.
<p>
Legal values are all positive numbers.
<p>
</dl>
</blockquote><h4>VALID STATES</h4><blockquote>
ALL - apart from T_UNINIT
</blockquote><h4>ERRORS</h4><blockquote>
On failure,
<I>t_errno</I>
is set to one of the following:
<dl compact>

<dt>[TBADF]<dd>The specified file descriptor does not refer to a transport endpoint.

<dt>[TBADFLAG]<dd>An invalid flag was specified.

<dt>[TBADOPT]<dd>The specified options were in an incorrect format or
contained illegal information.


<dt>[TBUFOVFLW]<dd>The number of bytes allowed for an incoming argument
<I>(maxlen)</I>
is greater than 0 but not sufficient to store the value of that argument.
The information to be returned in
<I>ret</I>
will be discarded.

<dt>[TNOTSUPPORT]<dd>This action is not supported by the transport provider.

<dt>[TOUTSTATE]<dd>The communications endpoint referenced by 
<I>fd</I>
is not in one of the states in which a call to this function is valid.

<dt>[TPROTO]<dd>This error indicates that a communication problem has been detected
between XTI and the transport provider for which there is no other
suitable XTI error
<I>(t_errno)</I>.

<dt>[TSYSERR]<dd>A system error has occurred during execution of this function.

</dl>
</blockquote><h4>RETURN VALUE</h4><blockquote>
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and
<I>t_errno</I>
is set to indicate an error.
</blockquote><h4>SEE ALSO</h4><blockquote>
<i><a href="t_accept.html">t_accept()</a></i>,
<i><a href="t_alloc.html">t_alloc()</a></i>,
<i><a href="t_connect.html">t_connect()</a></i>,
<i><a href="t_getinfo.html">t_getinfo()</a></i>,
<i><a href="t_listen.html">t_listen()</a></i>,
<i><a href="t_open.html">t_open()</a></i>,
<i><a href="t_rcvconnect.html">t_rcvconnect()</a></i>,
<xref href=chap5></xref>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
